package com.meshnetics.gb.type;

/**
 * Formatter is intended to provide conversion of values to different string formats. In most this string formats
 * aim human interaction. This general formatter interface doesn't specify any mandatory formats.
 *
 * @author AKovylin
 */
public interface Formatter {
    /**
     * Name of formater.
     *
     * @return name of formatter
     */
    String getFormatterName();

    /**
     * Returns <code>true</code> is formater supports values of specified type.
     * Formatters should not support types derived from types they support.
     *
     * @param valueType data type
     * @return <code>true</code> if formatter can format values of this type, <code>false</code> otherwise
     */
    boolean isTypeSupported(DataType valueType);

    /**
     * Returns <code>true</code> is formatter supports specified format.
     * <br><br>
     * Formats should be defined by formatters themselves so this method doesn't guarantee that passed
     * format code is the same format this formatter thinks of. If code provided by formatter itself it should be
     * always supported. This method aims models with all formats collected in distinct place and numbers of
     * formatters supporting subsets of all defined formats.
     *
     * @param format code of format
     * @return <code>true</code> if formatter supports specified format, <code>false</code> otherwise
     */
    boolean isFormatSupported(int format);

    /**
     * Returns string representation of value in accordance with specified format.
     *
     * @param value  value
     * @param format format code
     * @return formatted string representing specified value (and additional info if specified in format)
     * @throws NullPointerException     thrown if value is null
     * @throws IllegalArgumentException thrown if specified format is not supported or value of unsupported
     *                                  data type provided
     */
    String format(DataValue value, int format);
}
